Add an awi Web Service Data Source

To add an awi Web Service data source:

Choose New Data Source from the Project group of the Ribbon's Home tab. This will display a sub-menu of the different data source types.

Choose AWI Web Service.

The New AWI Web Service Data Source dialog box will be displayed.

Enter a name for this Data Source in the Name field. This name is used to reference the Data Source within your Project.

In the XML Schema field, enter the path and file name of an XML schema that describes the XML format of the data required by the web service transaction you want to use for this Data Source or click on the browse button, , to browse for the file.

Both XML and XML schema files are supported.

Alternatively, if you don't have an existing XML Schema file, you can use the Wizard button to create one manually. The wizard can also produce an asp file which can be used as a template from which to create your transaction when using Digitise Apps in conjunction with NDL's Robotic Process Automation toolkit.

Enter a URL for the awi Web Service location, such as http://myserver/awiwebservice2.asmx, or click on the browse button, , to browse for a WSDL file containing the required location.

Enter the name of a Transaction supported by the awi Web Service.

When you have finished, click on the OK button.

Your awi Web Service will now be listed in the Data Sources Pane – click on the Data Sources tab to display this pane if it isn't already in view. A new window will also appear in the Workspace, showing a tree view of your XML schema, looking something like this:

At the top of the tree, the 'Data Source node' is the name you gave this Data Source and branching off below this are sub-nodes representing the various elements of the schema. Double-click on a node to expand it and display the fields within it and double-click on the caption bar at the top of the list to hide the fields again. Alternatively, you can toggle the display of the node fields by clicking on the Arrow symbol to the right of a node name or right-clicking on a node name and choosing Expand from the context menu.

You now need to select those elements which you want to use within your Project. You do this in basically the same way as described for Database Data Sources except that you will be mapping XML elements rather than database columns.

Note, however, that you can only map elements from a SINGLE table; you cannot mix elements from multiple tables when using an awi Web Service as your Data Source.

Once you have mapped one or more XML elements, these elements will be displayed in the Data Sources Pane underneath the name you gave to this Data Source earlier in the New AWI Web Service Data Source dialog box. Clicking on a node in the tree view in the Data Sources Pane will display the Properties for that node in the Properties Pane. Editable Properties are displayed in black. Those which can't be edited are displayed in grey.

The following table lists some of the main Properties available for the different nodes:

Data Source Nodes

Name

The name you have given to refer to this Data Source in your Project. If you want to change the name of this Data Source, you can edit it here.

Device Database

Specifies the name of the local database on the mobile device in which you want your app to store data records for this Data Source. Leave at <default> if you want to use the default database to store this data or enter a name to be used for the database.

The name you enter here, Specify the name of the database file to use without the file extension. Note that for the Android, Apple and Windows Universal Platforms you cannot include a path with the file name.

You can share a database between different apps by prefixing the database name with %SHARE%\, e.g. %SHARE%\MyAppData. Shared databases are stored in the Digitise Apps Applications folder on the device instead of in the individual app specific folders so they can be accessible to all apps.

Device Table

Name of the table in the local database on the mobile device to store data for this Data Source.

Timeout

Number of seconds the Digitise Apps Client will wait for data to start being downloaded when a data download is requested at runtime.

You can also change this value on the App Server, using the App Manager utility, allowing you to easily adjust the interval without having to change your app.

Storage Mode

Select Disk to retain data in the Client Database, Memory for temporary data. On the Android, Apple and Windows Universal Platforms data is always stored on 'disk'.

Schema

Internal Resource name for the xml file used to define the Data Source.

Service

URL to be used to call the required web service page.

Transaction

The name of the Transaction within the awi Web Service you want to process data requests and uploads for this Data Source.

Username and Password

Use to allow App Server to impersonate a specific Windows user. Note the password is displayed as asterisks.

Overwrite Server Settings

For each Digitise app you publish to the App Server, there are a number of Properties relating to each Data Source which can be specified within App Manager. These Properties include the connection details and any username and password required to access the remote data source.

These Properties can be entered manually within App Manager or copied into App Manager, when the Project is published to the App Server, from the equivalent Properties specified within App Studio. Any values stored within App Manager will be used in preference to the values entered within App Studio. This allows you to modify some essential Properties for Data Sources without having to edit and republish your Project, e.g. to move temporarily from a live to a test data source. The Properties are specified within App Manager using the Data Sources button under the Properties tab for individual published apps.

The Overwrite Server Settings Property within App Studio allows you to specify whether you want the App Manager Data Source Properties to be overwritten by the equivalent values within a Project when you publish the Project to the App Server.

You specify a default value for this Property under the Project Properties but you can change this for each individual Data Source within the Project, if required.

Under the Project Properties, set this Property to True if you want the default action to be to overwrite the App Manager settings when you publish the Project or False if you want the default action to be not to overwrite them.

Under each individual Data Source, the default value for the Overwrite Server Settings Property is Default, which means it will use the value specified within the Project Properties. To use a different setting for an individual Data Source than the default setting, under the particular Data Source's Properties, change the Overwrite Server Settings Property's value from Default to True if you want the App Manager settings to be overwritten or False to retain the App Manager settings.

Data Item Mapping Nodes

Mapping

The name of the column for this data item within the database to be held locally on the device.

Primary Key

Set this Property to True if this data item is the Primary Key or part of a combination of columns making up the Primary Key for this Data Source. The Primary Key must be a unique value for each record.

Otherwise it should be set to False.

Default

Default value for this data.

Length

Specifies the maximum number of characters for this data item. The default value of 0 indicates that the default length is to be used, which is 4000 characters.

Allow Null

If this data item can contain Null values, this Property should be set to True, otherwise it should be set to False.

The value of this Property should match the equivalent property for the relevant column in the remote Target data source otherwise you may get errors when uploading or downloading data to or from this data item.

Read-Only

If set to True the value in this data item cannot be updated in an existing record on the mobile device. A value can only be entered in a new record.

By default, the Property is set to False, which means the data item can be updated in an existing record.

Ignore Invalid Control Characters

If set to True, any unrecognised control characters will be ignored when displayed on your mobile devices.

SQL Type Override

Allows you to specify a SQL data type to be used for this data item in the local database on the mobile device instead of the default data type assigned when the Data Source was created.

Auto

Allows you to automatically generate unique values for a data column when a record is created using the CreateRecord Method. You can use this option to populate an Identity field or generate a unique GUID value.

The default value is None, which means this data item will not be automatically assigned a value when the record is created.

Select GUID to enter a unique GUID value, in the form:

00000000-0000-0000-0000-000000000000

Note that the data column must have a GUID or string data type.

Select Identity to enter a unique Identity value. Selecting Identity displays two further Properties:

Identity Seed

Provides the starting numeric value.

Identity Increment

Specifies the amount to increment or decrease the Seed or last used value to generate the number when a new record is created.

Note that GUID and Identity values are only guaranteed to be unique within the local database table.

Once you have published an app you can change some of the above Properties, such as the URL, Username, Password and Timeout values, on the App Server using the App Manager utility allowing you to easily modify the connection details without having to change your app. For example, you can use this feature to change between live and test data sources. You can also change these same values programmatically within your Scripts, allowing you to include connection options within an app.